Common

api.ledControl(state)

Overview

Turns ON or OFF the on board LED. It can be also used for debugging purposes.

Arguments

• state (integer) - sets LED state (1=ON, 0=OFF)

Example

--turns on blue LED
api.ledControl(1)

api.delayms(ms,mode)

Overview

Pause the execution for ms milliseconds.

Arguments

• ms (integer) - The number of milliseconds to delay (in range from 0 to 2147483647)
• mode (integer)(optional) - use sleep in longer intervals:
  • 1 - if the interval ms is longer than 10 ms, sleep
  • 2 - sleep for defined amount of milliseconds

Example #1

api.delayms(1000) --delay one second

Example #2

api.ledControl(1) -- turn on blue LED
api.delayms(1000) -- wait 1 second
api.ledControl(0) -- turn off blue LED

Example #3

api.delayms(1000,2) -- sleep for one second, then continue in the process

api.randInt(min, max)

Overview

Generate random number within given range.

Available only for LoRaWAN devices (function uses it's module to generate random number)

Arguments

• min (integer) - beginning number of the interval (in range from 0 to 2147483647)
• max (integer) - end number of the interval (in range from 0 to 2147483647)

Return

• number (Integer)

Example

-- generates random number within interval from 5 to 20
ran=api.randInt(5, 20)

api.getUniqueNumber()

Overview

Calling this function increases uint32_t variable by one every time this function is called then it returns it's value. It's in range (in range from 0 to 2^32)*

Return

• num (integer) - Unique number (in range from 0 to 2^32)*

Example

--get an unique number
num = api.getUniqueNumber()

api.getBatteryVoltage()

Overview

Get curent battery voltage in mV.

Return

• voltage (Integer)

Example

--get battery voltage value in mV
mv = api.getBatteryVoltage()

api.getTick(int)

Overview

Returns current number of milliseconds since startup. Counts up to 2^32 and then restarts from 0. By default it's using RTC derived tick which is incremented during sleep, but it's possible to explicitly select systick, which isn't.

Arguments

• int (integer) (optional)
  • 2 to use RTC derived tick and return value in seconds
  • 1 to use RTC derived tick and return value in ms (default)
  • 0 to use systick (value in ms)
• int (integer) (optional) (if first argument is 0)
  • 1 - reset systick value to 0
  • 0 - do not reset the systick (default)

Return

• tick (integer) - Value according to argument (in seconds / milliseconds)

Example

--get a timestamp, can be used for timing
timestamp = api.getTick()
-- to show the amount of milliseconds you can use print() function
print(timestamp)

api.dumpArray(str, opt)

Overview

Prints contents of variable as hexadecimal string (dumps array into console)

Arguments

• str (string) - variable to print
• opt (string)(optional) - optional argument defining type of print
  • "normal" - printing method used by default
  • "raw" - prints only the raw values

Example

--print string "123ef" as hexadecimal
api.dumpArray("123ef")
-- output
-- 00 : 31 32 33 65 66

--print string "123ef" as hexadecimal raw
api.dumpArray("123ef","raw")
-- output
-- 31 32 33 65 66

api.float(op,form,arg1,arg2)

Overview

Performs operation with given floating point data.

Only if it's allowed by the firmware. Convert function available from FW version v2.5.1

Arguments

• op (string) - The operation to perform (“add” - addition, “sub” - substraction of arg2 from arg1, “mul” - multiplication, “div” - division of arg1 by arg2, “coerce” - coercion, unary operation using only arg1, “convert” - conversion of integer to float, unary operation using only arg1)

• form (string) - Two or three characters specifying the format of input/output data.

  • first position is for arg1.
  • second either specifies the format of arg2 or if last, specifies the format of return data, which are the same
  • by adding “N” to end of a string it coerces and returns little endian integer (OPTIONAL)

• arg1 (string) - The first operation argument, formated as specified in format.

• arg2 (string) - The second operation argument, formated as specified in format.

Return

• result (string, integer) - Returns result of operation, either 4 bytes little/big endian (depends on form parameter) IEEE 754 float or string float representation or integer value

Example #1

-- Multiply IEE 754 float with a floating point constant and return coerced value
-- S - string float representation, e.g. “2.234”
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string

ret = api.float("mul", "SSN", "12.8", "1000.0")
print(ret)
-- output = 12800

ret = api.float("mul", "SSS", "12.8", "1000.0")
print(ret)
-- output = 12800.0000

Example #2

-- hexadecimal interpretation of a number 12.8 is 0x414CCCCD (IEE 754)

x=string.char(0xCD,0xCC,0x4C,0x41)
ret = api.float("mul", "BSS", x, "1000.0")
print(ret)

-- output = 12800.0000

Example #3

-- Convert integer to IEE 754 float
-- N - Input in little endian integer(for convert only)/Returns ouput as little endian integer
-- I - Binary little endian integer representation as 4 characters/bytes in a string(for convert only).
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string
-- > - returns result as big endian, if used as output IEEE 754 representation as 4 characters/bytes in a string
-- < - returns result as little endian, if used as output IEEE 754 representation as 4 characters/bytes in a string (default value)

y=string.char(0xCD,0xCC,0x4C,0x42)
ret = api.float("convert", "IB", y)
api.dumpArray(ret)
-- output = 9A 99 84 4E

y=125
ret = api.float("convert", "NB>", y)
api.dumpArray(ret)
-- output = 42 FA 00 00

api.setVar(index, value, bool)

Overview

Saves a persistent variable value, can be used between different wake up iterations.

Arguments

1. index (integer) - Index of the variable to write, index 0 to 15 is available for RAM variables (lost on reset), index 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and index 48 to 1071 is available for variables stored in EEPROM (100k writes).
2. value (integer) - Value to store at index (in range from 0 to 2147483647)
3. bool (boolean)(optional) - Optional argument, which stores bitwise negation of stored value into address higher by one

OR

2. mode (string) - explicit memory mode, currently "bytes" mode supported
3. value (string) - string array buffer to write

Example

--set persistent variable value from index 1000 to value of 3424
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
api.setVar(1000, 3424)

Example (string)

myVariable = "This is some string to store to eeprom"
api.setVar(29, #myVariable) -- save the length for later readout
api.setVar(30, "bytes", myVariable) -- consumes in total ceil(#myVariable / 4) 32-bit indexes in EEPROM/RAM/HEE

api.getVar(index)

Overview

Returns persistent variable value, can be used between different wake up iterations.

Arguments

1. index (integer) - Index of the variable to read, 0 to 15 is available for RAM variables (lost on reset), 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and 48 to 1071 is available for variables stored in EEPROM (100k writes).
2. default (integer)(optional) - Default value, which is returned if value stored in the address is same as bitwise negation of value stored in address higher by one

OR

2. mode (string) - Mode to use, currently supported "bytes"
3. length (int) - Length in bytes to read

Returns

• value (integer)(string) - Value of the 32bit variable, or string.

Example

--get persistent variable value from index 1000
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
slotNumber = api.getVar(1000)

Example (string)

stringLength = api.getVar(29)
myReadout = api.getVar(30, "bytes", stringLength)
print(myReadout) -- should print "myVariable" content!

api.wakeUpAt(day, hour, minute, second)

Overview

Schedules the next wake up event of the device to provided day of month (day), hour, minute and second. The provided wake up date is therefore absolute and not relative as in wakeUpIn().

Arguments

• day (integer) - Day of month, range from 1 to 31
• hour (integer) - Hour, range from 0 23
• minute (integer) - Minute, range from 0 to 59
• second (integer) - Second, range from 0 to 59
• resetOnFail (integer) - Reboot device when setting of wake-up event failed (1 - true, 0 or nothing - false)

Return

• status (integer) - Execution status, 0 for success and -1 for error

Example

--schedules next wake up to the 25th, 2:22:58
status = api.wakeUpAt(25, 2, 22, 58)

api.wakeUpIn(day, hour, minute, second)

Overview

Schedules the next wake up event of the device after specified time interval. The provided wake up date is therefore relative and not absolute as in wakeUpAt(). Note: The input arguments are not limited, but the total period specified must not exceed 31 days. (e.g. hour = 40, days = 2 gives a period of 3 days and 16 hours).

Arguments

• day (integer) - Day, range from 0 to 31
• hour (integer) - Hour, range (in range from 0 to 2147483647)
• minute (integer) - Minute, range (in range from 0 to 2147483647)
• second (integer) - Second, range (in range from 0 to 2147483647)
• resetOnFail (integer) - Reboot device when setting of wake-up event failed (1 - true, 0 or nothing - false)

Return

• status (integer) - Execution status, 0 for success and -1 for error

Example

--schedules next wake up in 1 day and 122 minutes
status = api.wakeUpIn(1, 0, 122, 0)

api.getTimeDate()

Overview

Returns current date and time set on this device. The time can be synchronized over LoRa, or when uploading LUA script using LUA scripting interface.

Return

• year (integer) - Current year
• month (integer) - Current month
• day (integer) - Current day of month
• hour (integer) - Current hour
• minute (integer) - Current minute
• second (integer) - Current second

Example

--read current date and time
y,M,d,h,m,s = api.getTimeDate()

api.setTimeDate(...)

Overview

Set date and time on this device, or calculate the difference and synchronize the date and time using first argument "DIFF" (detail in Arguments).

Arguments

api.setTimeDate(year, month, day, hour, minute, second):

• Set date and time:
  • year (integer): Range from 2016 to any value greater than 2016.
  • month (integer): Range from 1 to 12.
  • day (integer): Range from 1 to 31.
  • hour (integer): Range from 0 to 23.
  • minute (integer): Range from 0 to 59.
  • second (integer): Range from 0 to 59.

api.setTimeDate("DIFF",year, month, day, hour, minute, second):

• calculate and check date based on values bellow, if there is a difference, synchronize:
  • year (integer): Range from 2016 to any value greater than 2016.
  • month (integer): Range from 1 to 12.
  • day (integer): Range from 1 to 31.
  • hour (integer): Range from 0 to 23.
  • minute (integer): Range from 0 to 59.
  • second (integer): Range from 0 to 59.

Example

--set date and time
api.setTimeDate(2022, 1, 31, 23, 59, 0)

api.voltageSourceState(arg1, arg2)

Overview

Turn ON/OFF voltage source.

Only for variants with voltage source.

The voltage option is available only for variant with adjustable option.

Arguments

• arg1 (integer) - (1=ON, 0=OFF) New generation (NG) of voltage source can also:

• "measure" - return source voltage value

• "set-comp-value" - set comparator value

• "get-comp-value" - get comparator value

• arg2 (integer)(optional) - sets the voltage (mV) to the closest possible value (Available for variant with adjustable option!)

Example

--turn on voltage source
api.voltageSourceState(1)
--turn off voltage source
api.voltageSourceState(0)

api.stdin(option, opt1, opt2, opt3)

Overview

Read stdin (standard input) data or control button (get status, wait for button).

This function is using serial line, therefore use of this function in an interactive console (GUI) is not possible.

Arguments

1. "start" api.stdin("start", size) Start reading serial line.
   • size (int)(optional) = memory size (default 1024)
2. "stop" api.stdin("stop") Stop reading serial line.
3. "waitbutton" api.stdin("waitbutton", timeout) Wait for button to get pressed
   • timeout (int)(optional) = 0 by default
4. "readbutton" api.stdin("readbutton") Read status of the button.
5. "read" api.stdin("read", maxsize) Read serial line.
   • maxsize (int)(optional) = maximu size of data (default 0)
6. "readblock" api.stdin("readblock", maxsize, timeout) Read until maximum size or timeout is reached.
   • maxsize (int)(optional) = maximu size of data (default 0)
   • timeout (int)(optional) = 0 by default
7. "readuntil" api.stdin("readuntil", maxsize, stopByte, timeout) Read until maximum size, specified byte or timeout is reached.
   • maxsize (int)(optional) = maximu size of data (default 0)
   • stopByte (int)(optional) = '\n' by default
   • timeout (int)(optional) = 0 by default

Return

1. "waitbutton" res=api.stdin("waitbutton", timeout) Returns:
   • res(int) = -1 if failed or time (in ms) when pressed since this function was called.
2. "read" num, data = api.stdin("read", maxsize) Returns:
   • num (int) = received amount of Bytes
   • data (string) = received data
3. "readblock" num, data = api.stdin("readblock", maxsize, timeout) Returns:
   • num (int) = received amount of Bytes
   • data (string) = received data
4. "readbuntil" num, data = api.stdin("readuntil", maxsize, stopByte)
   • num (int) = received amount of Bytes
   • data (string) = received data

api.stdout(out, size, offset)

Overview

Write to stdout (standard output) without adding line termination. Can be useful when implementing raw serial protocols.

Arguments

• out (string) - string buffer to print to serial console (without adding newlines, raw print)
• size (int)(optional) - size of out to print (default prints entire out in other words #out)
• offset (int)(optional) - number of bytes to skip in out (default 0)

api.bsprintf(binData, format, offset, endian)

Overview

Function for formatting binary stream data according to various format specifiers, including support for characters, integers, short and long integers, floats, and doubles.

Arguments

• binData (string) - string buffer to print to serial console (without adding newlines, raw print)
• format (string) - size of out to print (default prints entire out in other words #out)
• offset (int)(optional) - number of bytes to skip in out (default 0)
• endian (string)(optional) - "little" (default) or "big"

Supported formats:

• Character: c
• Short integers: hd, hi, hu, hx, hX, ho, hb, h
• Long long integers: lld, lli, llu, llx, llX, llo, llb, ll
• Integers: d, i, u, x, X, o, b
• Doubles: e, E, g, G, lf
• Floats: f, F

Example

-- binary string
x=pack.pack("b8",1,2,3,4,5,6,7,8)
-- memory print
api.dumpArray(x) -- 00 : 01 02 03 04 05 06 07 08

y=api.bsprintf(x,"%d") -- format 4-byte integer, little endian

print(y) -- output: 67305985

api.setVerbosity(num, opt)

Overview

Controls the amount of prints into the serial line.

Arguments

• num (integer) - sets general verbosity level

  • 0 - NONE
  • 1 - ERROR
  • 2 - WARNING
  • 3 - INFO (set by default)
  • 4 - SLOW
  • 5 - MAX

• opt (string)(optional) - specifying verbosity to specific function Here is a list of available specifiers depending on the version of the converter:

  • "LORA"
  • "LORA_HW"
  • "RADIO"
  • "LORA_TIMER"
  • "NBIOT"
  • "RTC"
  • "HWAPI_COMMON"
  • "HWAPI_DALI"
  • "HWAPI_DIO"
  • "HWAPI_DS18B20"
  • "HWAPI_LORA"
  • "HWAPI_MBUS"
  • "HWAPI_MEMORY"
  • "HWAPI_RS485"
  • "HWAPI_S0"
  • "HWAPI_SENSIRION"
  • "HWAPI_TIME"
  • "HWAPI_UART"
  • "HWAPI_WMBUS"
  • "WMBUS_HW"

To configure the timestamp, the specification of the arguments looks like this:

• num (integer) - sets verbosity level in case of "TIMESTAMP_MODE" specified

  • 0 - NONE
  • 1 - TICK
  • 2 - RTC_TICK
  • 3 - TIME
  • 4 - DATETIME

• opt (string)(optional) - specifier

  • "TIMESTAMP_MODE"

Example

--turn off timestamp
api.setVerbosity(0,"TIMESTAMP_MODE")

api.exec(command, arg1, arg2, ...)

Overview

Executes a system command or Lua fragment (additionaly uploaded Lua API extension, according to https://ieeexplore.ieee.org/document/8733437)

Arguments

• command (string)(optional) = command name or Lua API extension / fragment name

Commands:

1. "_get_wake_info"
   • returns 3 (NB-IoT: wake-up reason, serial status, NB-IoT serial status) or 2 (LoRaWAN: wake-up reason, serial status)
   • wake-up reason (string)
     • "button" - button was pressed
     • "serial" - serial interface connected
     • "timer" - RTC wake-up timer
   • serial status (string)
     • "connected" - serial line is connected
     • "disconnected" - serial line is disconnected (not detected)
   • NB-IoT serial status (string)
     • "active" - module serial output (transmit) is high - module is active
     • "inactive" - module likely sleeps, serial line is low
2. "_free_mem"
   • returns number of free heap memory in bytes
   • free heap (int) - free heap memory in bytes
3. "_sysinfo"
   • returns table with system information
   • value["SN"] - returns Serial Number of the device (-1 for old devices)
   • value["ver"] - firmware version in format 2.9.12 (major.minor.bugfix)
     • value ["ver"]["major"] - major firmware version
     • value ["ver"]["minor"] - minor firmware version
     • value ["ver"]["bugfix"] - bugfix firmware version
     • value ["ver"]["sha"] - sha reference to git repository
   • value["tim"] - build time
     • value ["tim"]["hour"] - build hour
     • value ["tim"]["min"] - build minute
     • value ["tim"]["sec"] - build second
   • value["date"] - build date
     • value ["date"]["yr"] - build year
     • value ["date"]["mon"] - build month
     • value ["date"]["day"] - build day of month
   • value["model"] - device model information
     • value ["model"]["name"] - *name of device model of ACR-CV, e.g. "ACR_CV_101N_W_D2_DEDICATED"*
     • value ["model"]["source"] - *power source name, "ac" or "battery"*
4. "_format_eeprom"
   • filler (integer)(optional)
   • erases internal device EEPROM to value 0xFF (unless second argument - filler - is defined)
   • deletes last Lua error report and all values set by api.setVar()
5. "_get_last_error"
   • report type (string) - type of report to read (default "SHORT")
     • "SHORT" - short descript of Lua error (line, and single sentence)
     • "TRACEBACK" - text traceback including global and local variables values (lzf-compressed)
     • "STDOUT" - last 1024 bytes of stdout prints before the crash (lzf-compressed)
     • "STDOUT_RAW" - as "STDOUT" but uncompressed, printable
     • "TRACEBACK_RAW" - as "TRACEBACK" but uncompressed, printable
     • "ALL" - "TRACEBACK" and "STDOUT" combined (lzf-compressed)
   • action (string) or start (int) - action to execute with given entry type
     • "len" - returns length of given type in bytes
     • "clear" - clears last error entry
     • or bytes offset (defaults to 0) since start of entry type to return
   • end (int) - end index of buffer to return, use -1 to return all
   • check LUA script for example usage
6. "_current_serial_log"
   • returns current serial log history (1024 bytes) as string
7. "_sleep"
   • seconds (int) (optional) - number of seconds to sleep (defaults to 0)
   • sleeps for provided number of seconds or if seconds is 0, sleeps without RTC timeout, use with caution!
8. "acrComTx"
   • data (string) - send payload as "acrCom" communication protocol frame, used internally with gui.acrios.com
9. "_reset" - resets the device, starting again by running bootloader
10. "_interactive_line_maxlen" - set or get max length of input for interactive mode
    • value (int) (optional) - size of input command buffer in bytes (defaults to -1)
    • in case -1 or no argument is provided, function returns currently set value (default is 2048 bytes)
    • if other value is provided, the newly allocated maximum value is returned - in case of failure, 0 is returned
11. "_cpu_temp" - get CPU temperature in degrees Celsius (+-5 deg.C)
    • returns temperature as integer
12. "_acrComHeader" - computes ACRCOM header, used for example in NWD Lua script
    • data (string) - string buffer to use to compute the header from
    • returns 7 bytes string buffer containing: [0x00][little endian data length (2 bytes)][bitwise negation of previous field (2 bytes)][CRC16-CCIT (2 bytes)]
    • CRC16 used can be computed using this python code:
13. "_print_mode" - print mode configuration
    • mode (string)
      • "ALL" - print even if no serial line is not connected (default)
      • "CONNECTED" - print only when serial line is connected
      • "NONE" - do not print
14. "clearSwWdogNoCom" - clears no-communication watchdog. If the function api.nbSend or loraSend isn't called for certain time, device resets. You can prevent this by using this function. (7 days by default)
15. "clearSwWdogNoSleep" - clear no-sleep watchdog. If device doesn't go to sleep for certain time, it resets. To prevent this from happening, you can call this function. (3 days by default)
16. "setSwWdogNoComReloadValue" - change value of no-communication watchdog. By default it's 7 days.
17. "setSwWdogNoSleepReloadValue" - change value of no-sleep watchdog. By default it's 3 days.
18. "_set_crlf_handler" - settings of CRLF handling
    • "noprint" - removes CRLF
    • "asis" - leaves CRLF as is
    • "space" - replaces CRLF with space
    • "newline" - Replaces CRLF with newline (\n)

def CB_calculateCrc16(data):
    def crc16_ccitt_update(byte, crc):
        # For each bit in the data byte, starting from the leftmost bit
        for i in range(7, -1, -1):
            # If leftmost bit of the CRC is 1, we will XOR with
            # the polynomial later
            xor_flag = (crc & 0x8000) != 0

            # Shift the CRC, and append the next bit of the
            # message to the rightmost side of the CRC
            crc = crc << 1
            if (byte & (1 << i)) != 0:
                crc = crc | 1

            # Perform the XOR with the polynomial
            if xor_flag:
                crc = crc ^ 0x1021
        return crc & 0xFFFF

    retCrc = 0xFFFF

    # last is the payload
    for i in range(len(data)):
        retCrc = crc16_ccitt_update(data[i], retCrc)

    # Augment 16 zero-bits
    for i in range(2):
        retCrc = crc16_ccitt_update(0, retCrc)
    return retCrc

19. "_has_new_reset_log" - flag showing whether asynchronous serial log was detected
    • returns flag as boolean
20. "_get_unix_time" - get time/date as single seconds value since the Epoch (1.1. 1970) (UNIX timestamp)
21. "_set_unix_time" - set time/date using UNIX format
22. "_serialInterrupt" - Serial Interrupt configuration
    • arg2 enable/disable - (true/false)
    • arg3 enable/disable wait for config inside of onWake function - (true/false)
23. "_sysclk" - set clock of the Microcontroller in Hz, options are:
    • 32000000 Hz (default)
    • 48000000 Hz
    • 24000000 Hz
    • 16000000 Hz
    • 2000000 Hz
    • 1000000 Hz
    • 800000 Hz
    • 400000 Hz
    • 200000 Hz
    • 100000 Hz
24. "_reset_reason" - returns string describing reset reason
25. "_sleep_mode" - set globally sleep mode (same mode as in api.delayms)
    • 1 - if the interval ms is longer than 10 ms, sleep
    • 2 - sleep for defined amount of milliseconds
26. "_keep_source_in_sleep" - only in case of converter variant with power supply - keep the supply ON during sleep mode
27. "_cc" - only if the couloumb counter is available - these arguments are available:
    • if no argument is called -> get values. List of return arguments:
      • 1 - result - result of register readout (0 - success, negative on error)
      • 2 - mAh - Accumulated charge in mAh
      • 3 - ESR - Equivalent Series Resistance estimate of battery (mOhm)
      • 4 - in100V - input (battery) voltage, when 100mA is sourced from battery (mV)
      • 5 - inV - input (battery) voltage, when battery is disconnected (ultra low power mode) (mV)
      • 6 - SC100 - output (super-capacitor) voltage, when 100mA is sourced from battery (mV)
      • 7 - SC - output (super-capacitor) voltage, when battery is disconnected (ultra low power mode) (mV)
      • 8 - Temp - temperature in deg. C
28. "_sc" - control supercapacitor, second argument has 3 options:
    • 1 - force connect supercapactior
    • 2 - force disconnect supercapacitor
    • 3 - leave supercapacitor as floating
29. "_SENSUS_BUP_parse" - parse Bubble Up Protocol message.
    • arguments:
      • 1 - Input data to parse
      • 2 - key (optional) - if no key is defined, the default key is used
      • 3 - key index (optional)
    • returns:
      • 1 - Meter ID
      • 2 - Value
      • 3 - Flags
      • 4 - Frame type
      • 5 - Original frame
30. "_hw_features" - check the hardware variant
    • arguments:
      • 1 - (optinal)(string) option to check, if empty, the full hardware report is returned
      • Can check for:
        • SIM7022 - if the SIM7022 module is present
        • SC - if supercapacitor is present
        • SC_CAP - if 1F - 220 F supercapacitor is present
        • NB - NB-IoT variant
        • SX1261 - SX1261 is present
        • CC - couloumb counter is present
        • SC_MNGMNT - management for supercapacitor is present
        • LIC - supercapacitor based on LiC is present
        • AC - EAC variant
        • MBUS - M-Bus variant
        • RS485 - RS485/Modbus variant
        • ADJSRC - variable aditional source is present
        • EXTSRC - aditional source is present
        • MBUSNG - new generation of MBUS
    • returns:
      • 1 - board Version
      • 2 - production Time
      • 3 - feature Set
      • 4 - Variant char 1
      • 5 - Variant char 2
      • 6 - Variant char 3
      • 7 - Variant char 4
      • 8 - Variant major
      • 9 - Variant minor
      • 10 - Variant bugfix
      • 11 - Variant formFactor

Return

• Varies according to command name, check command description.

Example

-- get converter model and power source

print(api.exec("_sysinfo")["model"]["name"]) --result e.g.: ACR_CV_101N_R_EAC

print(api.exec("_sysinfo")["model"]["source"]) --result e.g.: ac

hasNGMbus = api.exec("_hw_features", "MBUSNG:1")

print(hasNGMbus) -- return true/false

api.table(command, arg1, arg2, ...)

Overview

Interface to create and manipulate memory-efficient tables and maps. Check multimode script or sendOnce script for example usage.

Arguments

• command (string) - table operation, see operations bellow
  • "set-max-id"
    • max id (integer) - maximum table index, must be >= 1
  • "get-max-id" - reads previously set value
  • "new" - creates new table
    • table id (integer) - id of newly created table, please ise set-max-id first!
    • type (string) - type of the table
      • "U32" - table is a list of integers of unsigned 32bit length
      • "I8" - table is a list of signed 8bit integers
      • "U32-I8" - table is a map/dictionary with U32 as key and I8 as value
      • "STR" - table is a list of strings
    • max length (integer) - maximum number of table entries
  • "dispose" - deletes a table
    • table id (integer) - id of an existing table
  • "insert" - inserts a new value in a table
    • table id (integer)
    • if type is "U32" or "I8":
      • value (integer) - value to insert at the end of list
    • if type is "U32-I8":
      • key (integer) - key to use in the map/dictionary
      • value (integer) - value to store at given key entry
    • if type is "STR"
      • value (string) - string to insert
  • "index-of" - returns key or index number of first occurence of given value
    • table id (integer)
    • value (integer) - value to search a key for
  • "get-index" - read value at provided index
    • table id (integer)
    • index/key (integer) - returns value at given key/index
  • "set-index" - sets value at provided index/key
    • table id (integer)
    • index/key (integer) - key or index to set the value at
    • value (integer) - value to set
  • "used" - returns number of entries in given table
    • table id (integer)
  • "clear" - clear all entries in provided table id
    • table id (integer)

Return

• Varies according to command name, check command description.

Example

Here is an example of inserting a string into the table:

--Setup table--
api.table("set-max-id", 1)
api.table("new", 1, "STR", 100)

--Inserting the value--
api.table("insert", 1, "Hello")

--Getting the value--
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: Hello

--Getting index with the value--
s=api.table("index-of",1,"Hello") print(s)
--Response--
~> [STDOUT]: 1

--Getting the length of the index--
a=api.table("get-index-length",1,1) print(a)
--Response--
~> [STDOUT]: 5

--Clearing the table--
api.table("clear",1,1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: nil

--Removing table--
api.table("dispose",1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [HWAPI_COMMON]: Cannot index in non-existent table ID 1
~> [STDOUT]: -1

api.aes(operation, data, iv, key)

Overview

Function to encrypt or decrypt provided payload using a key and IV with AES-CTR.

For more detail and example see this section.

Arguments

• operation (string) - "encrypt" or "decrypt"
• data (string) - data to encode or decode
• iv (string) - 16 bytes of IV (initialization vector)
• key (string) - 16 bytes of key to use

Example

--assemble initialization vector
--fill wmbusID, wmbusID, transmissionCounter, transmissionCounter values
function getIV()
    return pack.pack("<I4", wmbusID, wmbusID, transmissionCounter, transmissionCounter)
end

--example of encryption (payload is the data to encrypt)
encpayload = api.aes("encrypt",payload, getIV(), key)